ParcelLabel API
Create Label(s) International Inbound to NZ (Offshore)
How to generate parcel labels for parcels being sent from overseas locations
When generating parcel labels for packages originating from outside of New Zealand, merchants are able to choose the shipping method for how the parcel will be delivered to its destination. NZ Post currently offers the following services for customers:
- International Courier (tracked) - courier service into New Zealand
- ETOE (Please speak to your NZ Post account manager). Refer to the Create Label(s) - International ETOE page
These services need to be enabled by NZ Post before a merchant can use the service. Please contact your NZ Post account manager to activate the service you require.
Resource URL
UAT:
https://api.uat.nzpost.co.nz/parcellabel/v3/labelsProduction:
https://api.nzpost.co.nz/parcellabel/v3/labelsA unique consignment_id is returned once the details of the request are stored in the labeling database. One or multiple labels can be generated within a consignment (for International Courier only)
Request Parameters
For each of these services, the parameter requirements are similar but each service has slightly different requirements and needs to use the relevant service code. In the following table, we have provided which fields are required in the label request for a particular service. Additional requirements for Courier Tracked services are listed beneath the standard parameters.
Code samples for each of these separate service types are displayed further down this page.
| Field Name | Description | Required for Courier? |
|---|---|---|
| carrier | Carrier of the parcel. Value must be COURIERPOST | Yes - CourierPost |
| orientation | Print orientation of the label. Value must be PORTRAIT or LANDSCAPE. Default value is LANDSCAPE. | No |
| logo_id | Unique identifier for merchants logo. The field is only relevant for Courier services | No |
| format | Format of the label. Value must be PDF or PNG. Default Value is PDF. | No |
| notification_endpoint | Merchants Webhook URL to receive notification when the label has been generated. | No |
| sender_reference_1 | Sender's reference for the consignment. Will be printed on the label. | No |
| sender_reference_2 | Sender's reference. Will be printed on the Invoice | No |
| account_number | Your NZ Post Billing Account number (9 or 5 series).This is highly recommended to pass in the API call to obtain your account rates. | No |
| label_dimensions | An object specifying the label dimensions (in mm) upon which to print the label. If you are passing this object then the value should be 150x100 or 174x100 or empty string. If it is empty then default value is 174x100. This field is only mandatory to generate 150x100 dimensions label. | No |
| paper_dimensions | An object containing the paper size upon which to print the label. See Paper Dimension Object Parameters below | No |
| paper_dimensions.width_cm | Width the label to be printed to. Default value is 17.4. Note: To print on a 150x100 label this value must be set to ‘15.0’ | No |
| paper_dimensions.height_cm | Height of the label to be printed to. Default value is 10 | No |
| paper_dimensions.stationery_size | Paper size upon which to print the label. Must be A4 or A5. | No |
| sender_details | An object containing the sender contact details. See Sender Details Object Parameters below. | Yes |
| sender_details.name | Name of the sender | Yes |
| sender_details.phone | Phone number of the sender. NO SPACES, DIGITS and '+' ONLY | No but highly desirable |
| sender_details.email | Email address of the sender. | No but highly desirable |
| sender_details.signatory | Name of the individual sending the parcel, this is used for customs purposes. | No |
| sender_details.company_name | Company name of the sender. | No |
| sender_details.site_code | Site code assigned to the address where the parcel will be picked up by the courier. This address is also used for the NZ Post manifest process. | Yes |
| sender_details.customs_code | Customs code of the sender. | No |
| receiver_details | An object containing the receiver contact details. See Receiver Details Object Parameters below | Yes |
| receiver_details.name | Name of the receiver | Yes |
| receiver_details.phone | Phone number of the receiver. NO SPACES, DIGITS and '+' ONLY | No but highly desirable |
| receiver_details.email | Email address of the receiver. | No but highly desirable |
| receiver_details.vat_number | The VAT or GST number of the receiver. The field should not be > 14 characters. | No |
| receiver_details.registration_number | Registration number of the receiver required for Delivery Location Options. | No |
| pickup_address | An object containing the sender pickup address details. See Pickup Address Rules and Parameters below | Yes (NB: this is used as the NZ return address for this service) |
| pickup_address Rules | Only one of the following is required: address_id (highly desirable) OR dpid(highly desirable) OR site_code (highly desirable) OR street, suburb, city, and postcode. Use the city for addresses without suburbs. Address_id and dpid can be obtained using ParcelAddress API. Account managers set up site codes. | |
| pickup_address.address_id | Address ID for the pickup address sourced from the ParcelAddress API | See pickup_address rules |
| pickup_address.dpid | Delivery Point ID for the pickup address sourced from the ParcelAddress API | See pickup_address rules |
| pickup_address.site_code | Site code of pickup address. Setup by Account Manager | See pickup_address rules |
| pickup_address.company_name | Company name of the pickup address | No |
| pickup_address.building_name | Building name of the pickup address. | No |
| pickup_address.street | Street name of the pickup address. | See pickup_address rules |
| pickup_address.suburb | Suburb of the pickup address | See pickup_address rules |
| pickup_address.city | City of the pickup address | See pickup_address rules |
| pickup_address.postcode | Postal or zip code of the pickup address. | See pickup_address rules |
| pickup_address.state | Regional, provincial or county name of the pickup address. | No |
| pickup_address.unit_type | Type of unit (if applicable) of the pickup address. | No |
| pickup_address.unit_value | Value of the unit type. | Yes if pickup_address.unit_type is not blank |
| pickup_address.floor | Floor of the pickup address. | No |
| pickup_address.country_code | Two character country code of the pickup address. | No (this must be set to NZ if has value) |
| delivery_address | An object containing the receiver delivery address details. See Receiver Address Object Parameters section | Yes |
| delivery_address Rules | country_code (mandatory) AND only one of the following is required: address_id (highly desirable) OR dpid(highly desirable) OR site_code (highly desirable) OR street, suburb, city, and postcode. Use the city for addresses without suburbs. Address_id and dpid can be obtained using ParcelAddress API. Account managers set up site codes. | |
| delivery_address.address_id | Address ID for the delivery address sourced from the ParcelAddress API | See delivery_address rules |
| delivery_address.dpid | Delivery Point ID for the delivery address sourced from the ParcelAddress API | See delivery_address rules |
| delivery_address.site_code | Site code of the pickup address. | See delivery_address rules |
| delivery_address.building_name | Building name of the delivery address. | No |
| delivery_address.company_name | Name of company that the parcel is being delivered to. | No |
| delivery_address.street_number | Street number of the delivery address. | No but highly desirable |
| delivery_address.street | Street name of the delivery address. | See delivery_address rules |
| delivery_address.suburb | Suburb of the delivery address | See delivery_address rules |
| delivery_address.city | City of the delivery address | See delivery_address rules |
| delivery_address.state | State of the delivery address | No |
| delivery_address.country_code | Two character country code of the delivery address. | Yes (this must be set to NZ) |
| delivery_address.postcode | Postal or zip code of the delivery address. | See delivery_address rules |
| delivery_address.unit_type | Type of unit (if applicable) of the pickup address. | No |
| delivery_address.unit_value | Value of the unit type. | Yes if delivery_address.unit_type is not blank |
| delivery_address.floor | Floor of the pickup address. | No |
| delivery_address.instructions | Delivery instructions for courier | No |
| parcel_details | An object containing the label details for each label in the consignment. See Parcel Details Object Parameters section | Yes |
| parcel_details.service_code | Code to represent a delivery service. For domestic labels where carrier is COURIERPOST and the parcel is a Satchel, see rules in the Envelope Sizes section. | Yes |
| parcel_details.add_ons | Array of ancillary codes. Please refer to the Add ons section below for further details. | No |
| parcel_details.return_indicator | Indications if the label is used for returning items. Values must be OUTBOUND or RETURN. | Yes |
| parcel_details.description | The box size name on the label for the dispatching person to choose the correct box for packing. | No |
| parcel_details.currency | The currency to indicate the value unit of contents in a parcel. | Yes if parcel_details.service_code is any of Return Base Services table |
| parcel_details.dimensions | An object containing the dimension details of a parcel. See Parcel Details - Dimension Object Parameters section. | Yes |
| parcel_details.dimension Rules | For Courierpost labels that aren't Courierpost satchels, only one of the following is required: length_cm, width_cm, and height_cm OR volume_m3 (highly desirable - only an option if carrier is Courierpost) | |
| parcel_details.dimensions.length_cm | Length of the parcel. | See parcel_details.dimension rules |
| parcel_details.dimensions.width_cm | Width of the parcel. | See parcel_details.dimension rules |
| parcel_details.dimensions.height_cm | Height of the parcel. | See parcel_details.dimension rules |
| parcel_details.dimensions.volume_m3 | Volume of the parcel. | See parcel_details.dimension rules |
| parcel_details.dimensions.weight_kg | Physical weight of the parcel in kilograms. | Yes |
| parcel_details.dangerous_goods | An object containing the hazard identification information of a parcel. See Parcel Details - Dangerous Goods Object Parameters section below | No |
| parcel_details.dangerous_goods.hazard_class | Classification of dangerous items in the parcel. Value must be from Hazard Identification Code List at: [http://www.ilo.org/legacy/english/protection/safework/cis/products/safetytm/tranann5.htm] | No |
| parcel_details.dangerous_goods.type_code | United Nations Dangerous Goods identification code for dangerous items in the parcel. Value must be 4 digits. | No |
| parcel_details.parcel_contents | An array containing content details of a parcel. | Yes if parcel_details.service_code is any of GST zero-rated Product Code in Return Base Services table |
| parcel_details.parcel_contents.content_number | Number specifying an item in the parcel. Value must be an integer between 1 to 20 inclusive. | Yes if parcel_details.service_code is any of GST zero-rated Product Code in Return Base Services table |
| parcel_details.parcel_contents.description | Description of the parcel contents. | Yes if parcel_details.service_code is any of GST zero-rated Product Code in Return Base Services table |
| parcel_details.parcel_contents.harmonised_system_tariff | Internationally standardized name and number of the classification of the parcel content. | No |
| parcel_details.parcel_contents.quantity | Quantity of units in the parcel. | Yes if parcel_details.service_code is any of GST zero-rated Product Code in Return Base Services table |
| parcel_details.parcel_contents.weight_kg | Weight of each individual unit in the parcel (kgs). | Yes if parcel_details.service_code is any of GST zero-rated Product Code in Return Base Services table |
| parcel_details.parcel_contents.value | Dollar value of each individual unit in the parcel. | Yes if parcel_details.service_code is any of GST zero-rated Product Code in Return Base Services table |
| parcel_details.parcel_contents.country_code | Country code of the location in which the content piece was produced or manufactured. Value must be 2 characters. | Yes if parcel_details.service_code is any of GST zero-rated Product Code in Return Base Services table |
Courier Base Services
The following are sample base service codes for International inbound parcel and satchel courier services
| GST inclusive Product Code | GST zero-rated Product Code | Product Code Description |
|---|---|---|
| IWOLP | IWXOLP | Overnight Parcel |
| IWOLE | IWXOLE | Economy Parcel |
| IWOLTPSDL | IWXOLTPSDL | Satchel (DLE) |
| IWOLTPSA5 | IWXOLTPSA5 | Satchel (A5) |
| IWOLTPSA4 | IWXOLTPSA4 | Satchel (A4) |
| IWOLTPSFS | IWXOLTPSFS | Satchel (FS) |
| IWOLTPSLF | IWXOLTPSLF | Satchel (LF) |
| IWOLTPSXL | IWXOLTPSXL | Satchel (XL) |
| IWOLTPSCT | IWXOLTPSCT | Satchel (CT) |
Return Base Services
The following are sample base service codes for International Economy Returns and Courier Returns services
| GST inclusive Product Code | GST zero-rated Product Code | Product Code Description |
|---|---|---|
| IWEROLE | IWXEROLE | Economy Returns Parcel |
| IWEROLTPSDL | IWXEROLTPSDL | Economy Return Satchel (DLE) |
| IWEROLTPSA5 | IWXEROLTPSA5 | Economy Return Satchel (A5) |
| IWEROLTPSA4 | IWXEROLTPSA4 | Economy Return Satchel (A4) |
| IWEROLTPSFS | IWXEROLTPSFS | Economy Return Satchel (FS) |
| IWEROLTPSLF | IWXEROLTPSLF | Economy Return Satchel (LF) |
| IWEROLTPSXL | IWXEROLTPSXL | Economy Return Satchel (XL) |
| IWEROLTPSCT | IWXEROLTPSCT | Economy Return Satchel (CT) |
| IWROLP | IWXROLP | Courier Returns Parcel (Overnight) |
| IWROLE | IWXROLE | Courier Economy Parcel (between Islands) |
| IWROLTPSDL | IWXROLTPSDL | Courier Returns Satchel (DLE) |
| IWROLTPSA5 | IWXROLTPSA5 | Courier Returns Satchel (A5) |
| IWROLTPSA4 | IWXROLTPSA4 | Courier Returns Satchel (A4) |
| IWROLTPSFS | IWXROLTPSFS | Courier Returns Satchel (FS) |
| IWROLTPSLF | IWXROLTPSLF | Courier Returns Satchel (LF) |
| IWROLTPSXL | IWXROLTPSXL | Courier Returns Satchel (XL) |
| IWROLTPSCT | IWXROLTPSCT | Courier Returns Satchel (CT) |
Courier Satchel Sizes
Where the parcel is a satchel (and you intend to send as a satchel), and the service code has not been selected via the ShippingOptions API, then the envelope size must be concatenated to the end of the service code before submitting the label request e.g. IWOLTPSFS
Below is a list of valid satchel sizes.
| Size Code | Description |
|---|---|
| A4 | A4 |
| A5 | A5 |
| DL | DLE |
| FS | Foolscap |
| LF | LineFlow |
| XL | Xtra Large |
| CT | CT |
Courier Add ons
The following are sample value add-ons.
| Add on Name | Description |
|---|---|
| IWSR or IWXSR | Courier Signature Required |
| IWPR & IWXPR | Courier Photo Required |
| IWOLRD or IWXOLRD | Courier Rural Delivery |
| IWOLSAT or IWXOLSAT | Courier Saturday Delivery |
| IWOLDG or IWXOLDG | Courier Dangerous Goods |
| IWXFR | Courier International Freight |
| IWXCL | Courier Customs Clearance |
Courier Add-on Rules
The following rules apply to add-on services included in a label request:
- Add-on services can only be present when the carrier is CourierPost
- Only one of the following can be present on the label request: IWXOLRD Courier Rural Delivery, IWXOLSAT Courier Saturday Delivery, or IWXOLDG Courier Dangerous Goods
- Signature required, IWXSR, may always be present
Merchants must ensure that when appropriate, the prepaid ticket corresponding to the requested add-on service is affixed to the parcel.
| Prepaid Ticket | Description |
|---|---|
| Green | Saturday delivery |
Example 1: Overnight CourierPost Outbound label for a single parcel (174x100mm)
{
"carrier": "COURIERPOST",
"orientation": "LANDSCAPE",
"format": "PDF",
"sender_reference_1": "Order 34234",
"sender_reference_2": "Sales",
"label_dimensions" : "174x100",
"paper_dimensions": {
"width_cm": 17.4,
"height_cm": 10.0
},
"sender_details": {
"name": "Daisy Duck",
"phone": "0211246987",
"site_code": 34533
},
"pickup_address": {
"country_code": "NZ",
"company_name": "Cartoon Company",
"street": "122 Kerwyn Avenue",
"suburb": "East Tamaki",
"city": "Auckland",
"postcode": "2013"
},
"receiver_details": {
"name": "Mickey Mouse",
"phone": "0224309792",
"email": "m.mouse@abc.co.nz"
},
"delivery_address": {
"company_name": "",
"street_number": "",
"street": "59 Tawa Road",
"suburb": "One Tree Hill",
"city": "Auckland",
"state": "",
"country_code": "NZ",
"postcode": "1061",
"instructions": "look out for dog"
},
"parcel_details": [
{
"service_code": "IWXOLP",
"return_indicator": "OUTBOUND",
"description": "Test description",
"dimensions": {
"length_cm": 50,
"width_cm": 20,
"height_cm": 20,
"weight_kg": 1.7
}
}
]
}```
Example 2: Overnight CourierPost Return for a single parcel (174x100mm)
{
"carrier": "COURIERPOST",
"orientation": "LANDSCAPE",
"format": "PDF",
"sender_reference_1": "Order ABC1",
"sender_reference_2": "Return",
"label_dimensions" : "174x100",
"paper_dimensions": {
"width_cm": 17.4,
"height_cm": 10.0
},
"sender_details": {
"name": "Daisy Duck",
"phone": "0211246987",
"site_code": 34533
},
"pickup_address": {
"country_code": "NZ",
"company_name": "Cartoon Company",
"street": "122 Kerwyn Avenue",
"suburb": "East Tamaki",
"city": "Auckland",
"postcode": "2013"
},
"receiver_details": {
"name": "Mickey Mouse",
"phone": "0224309792",
"email": "m.mouse@abc.co.nz"
},
"delivery_address": {
"company_name": "",
"street_number": "",
"street": "59 Tawa Road",
"suburb": "One Tree Hill",
"city": "Auckland",
"state": "",
"country_code": "NZ",
"postcode": "1061",
"instructions": ""
},
"parcel_details": [
{
"service_code": "IWXROLP",
"return_indicator": "RETURN",
"description": "Test description",
"currency": "NZD",
"dimensions": {
"length_cm": 50,
"width_cm": 20,
"height_cm": 20,
"weight_kg": 1.7
},
"parcel_contents": [{
"content_number": 1,
"description": "Holdem Purse (limited edition)",
"quantity": 1,
"weight_kg": 0.3,
"value": 67.10,
"country_code": "NZ"
}
]
}
]
}```
Example 3: Overnight CourierPost Outbound label and Overnight Return label (174x100mm)
{
"carrier": "COURIERPOST",
"orientation": "LANDSCAPE",
"format": "PDF",
"sender_reference_1": "NZSEMKO",
"sender_reference_2": "NZSEMKO",
"label_dimensions": "174x100",
"paper_dimensions": {
"width_cm": 17.4,
"height_cm": 10.0
},
"sender_details": {
"name": ".",
"phone": "6112345678",
"email": "",
"company_name": "",
"site_code": 34533
},
"pickup_address": {
"company_name": "D-CO LIMITED",
"building_name": "",
"unit_type": "",
"unit_value": "",
"floor": "",
"street": "Private Bag 211111",
"suburb": "Returns Centre",
"city": "Auckland",
"country_code": "NZ",
"postcode": "2154"
},
"receiver_details": {
"name": "John Smith",
"phone": "0211632789",
"email": ""
},
"delivery_address": {
"is_collection": false,
"building_name": "",
"company_name": "",
"unit_type": "",
"unit_value": "",
"floor": "",
"street": "192C Cliff View Drive",
"suburb": "Green Bay",
"city": "Auckland",
"country_code": "NZ",
"postcode": "0604",
"instructions": ""
},
"parcel_details": [
{
"service_code": "IWXOLP",
"add_ons": [],
"return_indicator": "OUTBOUND",
"description": "SALES",
"dimensions": {
"length_cm": 20,
"width_cm": 20,
"height_cm": 30,
"weight_kg": 2
}
},
{
"service_code": "IWROLP",
"add_ons": [],
"return_indicator": "RETURN",
"description": "RETURN",
"currency": "NZD",
"dimensions": {
"length_cm": 20,
"width_cm": 20,
"height_cm": 30,
"weight_kg": 2
},
"parcel_contents": [
{
"content_number": 1,
"description": "Holdem Purse (limited edition)",
"quantity": 1,
"weight_kg": 0.3,
"value": 67.10,
"country_code": "NZ"
}
]
}
]
}```
Example 4: Overnight CourierPost Outbound label and Economy Return label (150x100mm)
{
"carrier": "COURIERPOST",
"orientation": "LANDSCAPE",
"format": "PDF",
"sender_reference_1": "NZ12345",
"sender_reference_2": "NZ12345",
"label_dimensions": "150x100",
"paper_dimensions": {
"width_cm": 15.0,
"height_cm": 10.0
},
"sender_details": {
"name": ".",
"phone": "6112345678",
"email": "",
"company_name": "",
"site_code": 34533
},
"pickup_address": {
"company_name": "The Widget Company",
"building_name": "",
"unit_type": "",
"unit_value": "",
"floor": "",
"street": "Private Bag 211111",
"suburb": "Returns Centre",
"city": "Auckland",
"country_code": "NZ",
"postcode": "2154"
},
"receiver_details": {
"name": "Jane Doe",
"phone": "0211632789",
"email": ""
},
"delivery_address": {
"is_collection": false,
"building_name": "",
"company_name": "",
"unit_type": "",
"unit_value": "",
"floor": "",
"street": "192C Cliff View Drive",
"suburb": "Green Bay",
"city": "Auckland",
"country_code": "NZ",
"postcode": "0604",
"instructions": ""
},
"parcel_details": [
{
"service_code": "IWXOLP",
"add_ons": [
"IWXSR"
],
"return_indicator": "OUTBOUND",
"description": "SALES",
"dimensions": {
"length_cm": 20,
"width_cm": 20,
"height_cm": 30,
"weight_kg": 2
}
},
{
"service_code": "IWXEROLE",
"add_ons": [],
"return_indicator": "RETURN",
"description": "RETURN",
"currency": "NZD",
"dimensions": {
"length_cm": 20,
"width_cm": 20,
"height_cm": 30,
"weight_kg": 2
},
"parcel_contents": [
{
"content_number": 1,
"description": "Holdem Purse (limited edition)",
"quantity": 1,
"weight_kg": 0.3,
"value": 67.10,
"country_code": "NZ"
}
]
}
]
}```
Example 5: Economy Return label for a single parcel (150x100mm)
{
"carrier": "COURIERPOST",
"orientation": "LANDSCAPE",
"format": "PDF",
"sender_reference_1": "DSH-1",
"sender_reference_2": "DSH-1",
"paper_dimensions": {
"width_cm": 15.0,
"height_cm": 10.0
},
"label_dimensions": "150x100",
"sender_details": {
"name": "Nigel Mustard",
"phone": "08001234568",
"email": "info@hotdog.com",
"company_name": "NZ Hotdog Company",
"site_code": 34533
},
"receiver_details": {
"name": "Donald Burger",
"phone": "0218978569",
"email": "nig.el@gmail.com"
},
"pickup_address": {
"company_name": "ABC Limited",
"street": "PO Box 12345",
"suburb": "Returns Centre",
"city": "Auckland",
"country_code": "NZ",
"postcode": "2154"
},
"delivery_address": {
"street": "29 Stafford Street",
"suburb": "Dunedin Central",
"city": "Dunedin",
"country_code": "NZ",
"postcode": "9011"
},
"parcel_details": [
{
"service_code": "IWXEROLE",
"return_indicator": "RETURN",
"description": "Default",
"currency": "NZD",
"dimensions": {
"length_cm": 1.0,
"width_cm": 1.0,
"height_cm": 1.0,
"weight_kg": 0.376
},
"parcel_contents": [
{
"content_number": 1,
"description": "Holdem Purse (limited edition)",
"quantity": 1,
"weight_kg": 0.3,
"value": 67.10,
"country_code": "NZ"
}
]
}
]
}```
Response Parameters
| Field Name | Description | Mandatory |
|---|---|---|
| consignment_id | Unique identifier for the consignment if the request is successful. | Yes |
| message_id | A unique ID for the API call | Yes |
| success | Returns true if request is successful. Returns false if request is not successful. | Yes |
Sample Response
{
"consignment_id": "DVZQYF",
"message_id": "520f4fa0-22cc-11eb-b1e1-027414412442",
"success": true
}